Repository navigation
feat: add unified OTel plugin factory - #905
Conversation
By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license. ### Issue Link, if available Closes #1170. Related implementations: [Java #872](aws/aws-durable-execution-sdk-java#872), [Python #904](aws/aws-durable-execution-sdk-python#904). ### Description Users can select either OTel view through `createOtelPluginFactory()`, with execution as the default and `{ mode: "invocation" }` selecting invocation mode. The factory snapshots existing configuration values and returns the original implementation's factory, preserving its registration metadata and per-invocation lifecycle. Existing factory exports and provider subpaths remain supported. The package root now exports the existing lazy execution provider, allowing `DURABLE_EXECUTION_PLUGINS=@aws/durable-execution-sdk-js-otel` without handler-side plugin registration. The provider/exporter must still be configured by ADOT or the application. ### Demo/Screenshots ```typescript import { createOtelPluginFactory } from "@aws/durable-execution-sdk-js-otel"; createOtelPluginFactory(); createOtelPluginFactory({ mode: "invocation", enrichLogger: false }); ``` Both results are factories for the handler's `plugins` list. The README and new `otel/unified-factory` example demonstrate registration and durable resume. ### Design Design note: #1170 describes the selector design. 1. **Problem:** Selecting a view requires different imports, and environment loading has no default package-root entry point. 2. **Cause:** The package exposes two separate factory constructors and two provider subpaths. 3. **Options:** Replacing the old factories breaks callers; merging the implementations adds unnecessary lifecycle and telemetry risk. A small selector can reuse the existing factories unchanged. 4. **Chosen:** Export `createOtelPluginFactory(options?)`, following the existing `createExecutionOtelPluginFactory` and `createInvocationOtelPluginFactory` naming. Resolve mode once, reject unsupported modes, and return the selected factory directly. Re-export the existing execution provider at the root to retain lazy initialization and metadata without another wrapper. 5. **Removals:** None. No SDK invariant or telemetry behavior changes. Net OTel runtime source change: +36 lines. Three new named exports: `createOtelPluginFactory`, `OtelPluginFactoryOptions`, and `durableExecutionPluginProvider`. Root cause for a bug fix: not applicable; this is an additive feature. ### Assumptions - Factory registration, exclusivity, concurrent execution isolation, and replay are exercised with the current real core SDK and local runner. Provider behavior is tested with the actual OpenTelemetry SDK and in-memory exporter. - Packed ESM/CommonJS exports, package-root environment loading, both existing subpaths, and public typings were checked using isolated installed-package fixtures rebuilt from this checkout. - **Unverified:** Live Lambda/ADOT deployment and Node.js 22 runtime execution. Local validation used Node.js 24.21.0; no AWS deployments were run. ### Decisions not covered by the issue or the design note - The unified entry point is a plain `createOtelPluginFactory` function, matching the existing JavaScript factory API and avoiding a public holder object. It returns the selected factory unchanged. - Invalid explicit modes, including `null`, throw `TypeError`; omitted/undefined modes default to execution. - `createOtelPluginFactory(options)` shallow-copies the configuration when the factory is created, so later assignments to the caller's options cannot change the selected configuration. The existing factories keep their current behavior: they read the original configuration object on the first invocation. - The unified-factory example is `localOnly: true`: its test retains workflow/history coverage, while the OTel integration test covers telemetry in both modes. This avoids a redundant cloud deployment and intentionally leaves the example out of `template.yml`. - Exact-optional consumer checks use `skipLibCheck` for existing unrelated core logger declaration errors, matching the established installed-header fixture. A separate normal strict check validates declarations without that skip. ### Checklist - [x] I have filled out every section of the PR template - [x] I have thoroughly tested this change - [x] Every new branch has a test that fails without it (default/execution, invocation, and invalid mode) - [x] For a bug fix: not applicable - [x] Every edited test expectation is listed: the new invalid-mode test now checks `TypeError` as well as the existing error message, protecting the documented error contract. No pre-existing test expectations were changed. ### Testing - Focused OTel factory unit, composed, integration, and packaged-consumer tests: **4 files, 27 tests passed**. Global setup rebuilt core, testing SDK, and OTel CJS/ESM/declarations first. These cover mode selection, configuration forwarding, registration/exclusivity, replay/concurrency, and packed ESM/CommonJS imports and public typings for `createOtelPluginFactory`. - `npx tsc --noEmit --project packages/aws-durable-execution-sdk-js-otel/tsconfig.json`: passed. - `npm run lint -- --max-diagnostics=20`: passed, 1,329 files checked. - The unified-factory example's local test passed against the rebuilt candidate packages, including recorded-history validation. - The actual SAM generator was checked with the example's `localOnly` configuration: it excludes the example from local and integration templates; a negative control with `localOnly: false` emits the function. #### Unit Tests Added default/explicit selection, configuration forwarding, factory identity/registration metadata, invalid-mode error type and message, mode snapshotting, and import/provider laziness checks. #### Integration Tests Added real-loader exclusivity checks, concurrent public handlers with suspension/replay, and packed ESM/CommonJS/type/environment-loading checks. No new language-neutral conformance requirement is needed because telemetry semantics are unchanged. #### Examples Added `otel/unified-factory` with a durable step/wait/resume workflow and a local-only recorded-history test. The sample is excluded from generated SAM templates and cloud integration deployment; telemetry assertions remain in the OTel package integration test. Updated OTel README usage and environment-loading guidance. ### Companion SDK pull requests - [Java](aws/aws-durable-execution-sdk-java#873) - [Python](aws/aws-durable-execution-sdk-python#905) These SDK changes can merge independently. Cross-language guide updates can follow the corresponding package releases. --------- Co-authored-by: Silan He <16982279+SilanHe@users.noreply.github.com>
Review feedback on aws#905. The quick start and the handler example had moved to `create_otel_plugin_factory()`, which is Workflow-rooted, silently changing the span tree this guide documents and illustrates. Both are back on `mode="invocation"`, matching the logger example, with a pointer to Trace Structure for the execution shape. Correct "returns the existing factory directly": every call constructs a new factory, so two of them in `plugins` are rejected as a duplicate in the `durable-otel-view` group. State what `otel,otel-execution` actually does -- one factory, the second skipped by identity, a warning logged -- and that Java rejects the same pair, so a multi-alias value is not portable across SDKs. Accept a `mode` read from configuration at runtime, which is a plain `str` and matched neither literal overload. Skip the installed entry-point test when the distribution is absent, since the declared entry points are already covered from pyproject.toml, and cover `otel,otel-invocation` in both orders to pin the matrix the Java suite pins.
Review feedback on aws#905. `test_factory_preserves_configuration_and_registration` compared `factory.exclusive_group` to `expected.exclusive_group`, where `factory` is an instance of `expected`. That is the same attribute on both sides, so it held for any value and the assertion verified nothing. This is what let `durable-otel-view` -- the Java SDK's group name -- sit in the README and the docstring until `e4a5614a`: the test looked like it pinned the value. Assert the literal `aws-durable-execution-otel-view` instead, matching how the Java suite pins its own group name.
| Listing `otel` with `otel-invocation` names two different views and raises | ||
| `PluginLoadError`. The Java and JS/TypeScript SDKs enforce the same one-view | ||
| contract but report a redundant second alias in their own idiom — Java rejects | ||
| `otel,otel-execution` outright — so do not rely on a multi-alias value behaving | ||
| identically across languages. |
There was a problem hiding this comment.
nit: can drop the same sentence here as well: "The Java and JS/TypeScript SDKs enforce the same one-view
contract but report a redundant second alias in their own idiom — Java rejects
otel,otel-execution outright — so do not rely on a multi-alias value behaving
identically across languages."
🤖 AI-assisted comment
| Each call constructs a new `ExecutionOtelPluginFactory` or | ||
| `InvocationOtelPluginFactory` of the selected view, carrying that class's | ||
| `exclusive_group`. Calls are not memoized, so register exactly one: two | ||
| factories of the same view in `plugins` are rejected at registration as a | ||
| duplicate in the `aws-durable-execution-otel-view` exclusive group. Both existing factory | ||
| classes remain supported, with unchanged configuration and behavior. |
There was a problem hiding this comment.
One failure mode isn't documented or tested: plugins=[create_otel_plugin_factory()] combined with DURABLE_EXECUTION_PLUGINS=otel raises PluginLoadError ("registered more than once in exclusive group"). The identity skip in plugin_discovery.py:504 doesn't apply because each call returns a new instance rather than the EXECUTION_OTEL_PLUGIN_FACTORY singleton, so the same-type check at :367 rejects it. The loader's docstring presents "same object passed explicitly and named in the env" as supported, which the selector can't satisfy. Suggest a README sentence (point mixed users at EXECUTION_OTEL_PLUGIN_FACTORY) plus an e2e test.
🤖 AI-assisted comment
| def test_installed_entry_points_preserve_alias_identity() -> None: | ||
| installed = { | ||
| entry.name: entry.load() | ||
| for entry in entry_points(group="aws_durable_execution.plugins") | ||
| if entry.name in {"otel", "otel-execution", "otel-invocation"} | ||
| } | ||
| if not installed: | ||
| pytest.skip( | ||
| "aws-durable-execution-sdk-python-otel is not installed in this " | ||
| "environment; test_plugin_factory.py covers the declared entry " | ||
| "points from pyproject.toml" | ||
| ) | ||
| assert installed == { | ||
| "otel": EXECUTION_OTEL_PLUGIN_FACTORY, | ||
| "otel-execution": EXECUTION_OTEL_PLUGIN_FACTORY, | ||
| "otel-invocation": INVOCATION_OTEL_PLUGIN_FACTORY, | ||
| } |
There was a problem hiding this comment.
nit: This repeats test_plugin_factory.py:161-168, which already checks the otel entry point against pyproject.toml. The pytest.skip also doesn't buy much: test_view_registration.py:425 and :443 need the same installed entry points and don't skip. Suggest deleting this test.
🤖 AI-assisted comment
| Calls are not memoized — | ||
| `create_otel_plugin_factory() is create_otel_plugin_factory()` is `False` — so | ||
| register exactly one. Two factories of the same view in `plugins` raise | ||
| `PluginLoadError` as a duplicate in the `aws-durable-execution-otel-view` exclusive group. A | ||
| `mode` read from configuration at runtime is accepted and type-checks as the | ||
| union of both return types. |
There was a problem hiding this comment.
nit: "Calls are not memoized, register exactly one" appears here, in the setup section (:72), and in the function docstring. The new README section is ~70 lines for a small selector. Maybe in a future PR, we can try to be more concise in our README
🤖 AI-assisted comment
| return ExecutionOtelPluginFactory(config) | ||
| if mode == "invocation": | ||
| return InvocationOtelPluginFactory(config) | ||
| raise ValueError("mode must be 'execution' or 'invocation'") |
There was a problem hiding this comment.
nit: now that a runtime str is accepted, it would help to show the rejected value, e.g. raise ValueError(f"mode must be 'execution' or 'invocation', got {mode!r}").
🤖 AI-assisted comment
| @@ -0,0 +1,112 @@ | |||
| """Public factory selection, typing, and installed entry-point coverage.""" | |||
There was a problem hiding this comment.
nit: there's no otel_plugin.py module, so this file doesn't mirror one. CONTRIBUTING asks for one test file per module; consider folding these tests into tests/test_plugin_factory.py.
🤖 AI-assisted comment
| assert len(invocations) == 2 | ||
| operation = next(span for span in spans if span.name == "work") | ||
| expected_parents = workflows if mode == "execution" else invocations | ||
| assert any(operation.parent == parent.context for parent in expected_parents) |
There was a problem hiding this comment.
nit: any(operation.parent == ...) is weak in invocation mode. Asserting the parent is specifically the first Invocation span would make this check meaningful.
🤖 AI-assisted comment
|
@SilanHe Thank you for your comments. Replied to one of them. And the remaining gaps exist in tests and docs. I will follow up with a new PR. |
Issue #, if available
Closes #904.
Description of changes
Users can import
create_otel_plugin_factoryand registercreate_otel_plugin_factory()for the execution view orcreate_otel_plugin_factory(config, mode="invocation")for the invocation view. Each call constructs a new factory of the selected view's class, passingconfigthrough unchanged and carrying that class'sexclusive_groupand registration metadata; the SDK then builds a fresh plugin for each invocation. Calls are not memoized, so register exactly one: two factories of the same view inpluginsare rejected at registration as a duplicate in theaws-durable-execution-otel-viewexclusive group. Existing released factory APIs remain supported.DURABLE_EXECUTION_PLUGINS=otelselects the existing default execution factory. It resolves to the same object asotel-execution, so listing both loads a single factory: the loader skips the second by identity and logs a warning. Listingotelwithotel-invocationnames two different views and raisesPluginLoadError. The Java SDK builds a separate factory per provider and rejectsotel,otel-executionoutright, so a multi-alias value is not portable across SDKs; the README tells operators to set exactly one name.The README and the existing logger example demonstrate the new API and the provider/layer prerequisites. The quick start and the
index.pyhandler example stay onmode="invocation", which is the view this guide's trace examples and screenshots document; moving them to the no-mode default would have silently changed the documented span tree.Register one returned factory in the handler's
pluginslist.Design
create_otel_plugin_factoryfunction in the existing factory module, constructing the selected view's factory, plus an entry-point alias. This keeps one import while reusing initialization, validation, and invocation behavior.Literalmodes and astrmode for a value read from configuration at runtime — plus theotelentry point. There is no holder class or additional runtime module.Validation and assumptions
Validated at commit
1ea4d0fc25a945b10d8ba13768edbbdac03ed44bin CI run 41887190850. All Python 3.11, 3.12, 3.13, and 3.14 build jobs passed.The Python 3.13 job confirms:
stroverloads.Provider and lifecycle checks use the actual core SDK and OpenTelemetry SDK with in-memory exporters. Live Lambda/ADOT/X-Ray export remains unverified; cloud tests were skipped in this run.
Decisions not covered by the issue or the design note
Nonefor mode raisesValueError, like other unsupported values. Omission selects execution mode.moderead from configuration at runtime. A plainstrmatched neitherLiteraloverload even though it works, and an unsupported value still raisesValueError.Edited test expectations
oteland assert identity with the existing execution factory.otel,otel-invocationin both orders.test_installed_entry_points_preserve_alias_identityskips when the distribution is not installed in the environment, because the declared entry points are already covered frompyproject.tomlintest_plugin_factory.py.Checklist
By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.
Companion pull requests
These SDK changes can merge independently. Cross-language guide updates can follow the corresponding package releases.